home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1998 September / Macworld (1998-09).dmg / Shareware World / Info / For Developers / MacZoop 1.8.3 / More Classes / Window Classes / ZDialog.h < prev    next >
Text File  |  1998-06-29  |  11KB  |  315 lines
  1. /*************************************************************************************************
  2. *
  3. *
  4. *            MacZoop - "the framework for the rest of us"         
  5. *
  6. *
  7. *
  8. *            ZDialog.h            -- a dialog box
  9. *
  10. *            
  11. *
  12. *
  13. *
  14. *            © 1996, Graham Cox
  15. *
  16. *
  17. *
  18. *************************************************************************************************/
  19.  
  20. #pragma once
  21.  
  22. #ifndef __ZDIALOG__
  23. #define    __ZDIALOG__
  24.  
  25. #ifndef __ZWINDOW__
  26. #include    "ZWindow.h"
  27. #endif
  28.  
  29. // dialog item extra info record, used for edit field control and radio button groups. NOTE:
  30. // Do not rely on the format of this structure not changing. It is the place ZDialog stores
  31. // private item info and is likely to be extended in future.
  32.  
  33. typedef struct
  34. {
  35.     union
  36.     {
  37.         unsigned short    flags;                // bitfield for edit field behaviour
  38.         short            groupID;            // group ID for radio button groups
  39.     };
  40.     union
  41.     {
  42.         long            minValue;            // for limited fields, the minimum value
  43.         TEHandle        mirrorTE;            // for password fields, the mirror TE record
  44.                                             // (n.b. p/w fields can't have limits [why would they?])
  45.     };
  46.     long            maxValue;                // -"-, the maximum value    
  47. }
  48. DItemInfo, *DItemInfoPtr, **DItemInfoHdl;
  49.  
  50. // flags bitfield used in above record:
  51.  
  52. enum
  53. {
  54.     editFieldIsDisabled         = 1,        // edit field is completely disabled
  55.     editFieldSignedInteger        = 2,        // edit field only accepts numbers and - sign
  56.     editFieldSignedFloat        = 4,        // as above plus decimal point character
  57.     editFieldUnsignedInteger    = 8,        // accepts only numbers but not - sign
  58.     editFieldUnsignedFloat        = 16,        // as above plus decimal point character
  59.     editFieldHasMinValue        = 32,        // if int field, has an acceptable minimum val
  60.     editFieldHasMaxValue        = 64,        // if int field, has an acceptable maximum val
  61.     editFieldAlphabeticOnly        = 128,        // only accepts letters, not numbers
  62.     editFieldHiddenChars        = 256,        // "password" style field hides input when typing
  63.     editFieldHCMirrorAlloc        = 0x8000,    // the password mirror has been allocated
  64.     efSignedLimitType            = editFieldSignedInteger + editFieldHasMinValue + editFieldHasMaxValue,
  65.     efUnsignedLimitType            = editFieldUnsignedInteger + editFieldHasMinValue + editFieldHasMaxValue
  66. };
  67.  
  68. // Password Fields, please note:
  69. // To establish a password field, set the flag <editFieldHiddenChars> (256) in your resource. When the
  70. // dialog is set up, this triggers the creation of a TextEdit record to hold the characters you type while
  71. // the user sees bullet points on the screen. The TE record is created by the first call to SetEditFieldInfo
  72. // with the flag set. This method then sets the <editFieldHCMirrorAlloc> flag, to indicate that a TextEdit
  73. // record was created. Subsequent calls to SetEditFieldInfo() won't create more records as long as this flag
  74. // is set. You can use GetValueAsText() to retrieve the true data from a password field. Pasting into such
  75. // a field is prevented, and cutting or copying from the field copies the bullet points- you can only get
  76. // the true data programmatically, which is how it should be. NEVER set the <editFieldHCMirrorAlloc> flag
  77. // yourself or in the resource, or things will quickly die.
  78.  
  79. // 'ictb' parsing stuff:
  80.  
  81. #if PRAGMA_ALIGN_SUPPORTED
  82. #pragma options align=mac68k
  83. #endif
  84.  
  85. // first part of resource is array of these:
  86.  
  87. typedef struct
  88. {
  89.     unsigned short    iData;            // item data flags (enumerated below)
  90.     unsigned short    iOffset;        // offset to data table
  91. }
  92. ictbItemEntry, *ictbPtr, **ictbHandle;
  93.  
  94. // text info stored in tables like this:
  95.  
  96. typedef struct
  97. {
  98.     short            txtFont;        // font ID or offset to name
  99.     Style            txtFace;        // face- plain, bold, etc
  100.     char            filler;
  101.     short            txtSize;        // font size
  102.     RGBColor        txtFColour;        // text colour
  103.     RGBColor        txtBColour;        // background colour
  104.     short            txtMode;        // transfer mode
  105. }
  106. ictbTextStyleTable, *ictbTablePtr;
  107.  
  108. // iData is bitfield arranged thus:
  109.  
  110. enum
  111. {
  112.     fFamChange        = 1,            // change the font
  113.     fFaceChange        = 2,            // change the face
  114.     fSizeChange        = 4,            // change the size
  115.     fFColourChange    = 8,            // change the colour
  116.     fAddFontSize    = 16,            // add the size
  117.     fBColourChange    = 8192,            // change the background colour
  118.     fModeChange        = 16384,        // change the mode
  119.     fIsFNameOffset    = 32768            // txtFont is offset to font name
  120. };
  121.  
  122.  
  123. #if PRAGMA_ALIGN_SUPPORTED
  124. #pragma options align=reset
  125. #endif
  126.  
  127. // message sent to dialog's boss when dialog closed OK. You can listen for this
  128. // so that you get informed when the user closes the dialog. The boss listens for
  129. // this anyway- you just need to override ReceiveMessage to take action.
  130.  
  131. enum
  132. {
  133.     kMsgDialogSuccessfullyClosed = 'dlg$',
  134.     kMsgDialogCancelled             = 'dlg-',
  135.     kMsgDialogItemClicked         = 'dlg~',
  136.     kMsgDialogSetUp                 = 'dlg!'
  137. };
  138.  
  139. // set up streaming stuff:
  140.  
  141. DEFINECLASSID( ZDialog, 'zdlg' );
  142.  
  143.  
  144. // class definition
  145.  
  146. class    ZDialog : public ZWindow
  147. {
  148. protected:
  149.     Boolean            isModal;        // TRUE if dialog is modal
  150.     Boolean            isInline;        // Dialog being handled by RunModal()- caller deletes.
  151.     DItemInfoHdl    dItemInfo;        // extra info about dialog items
  152.     ictbHandle        ictb;            // local handle to ictb resource, if any
  153.     short            signalDismiss;    // set to ok or cancel to close dialog safely in response to messages
  154.     short            exitItem;        // set to the item that dismissed the dialog, used by RunModal().
  155.     short            baseItems;        // count of "native" items in the dialog
  156.     
  157. public:
  158.     
  159.     ZDialog( ZCommander* aBoss, const short dialogID );
  160.     ZDialog();
  161.     virtual ~ZDialog();
  162.     
  163.     // window handling stuff
  164.     
  165.     virtual void    InitZWindow();
  166.     virtual void    Draw();
  167.     virtual Boolean    Close(const short phase);
  168.     virtual void    AdjustCursor(const Point mouse, const short modifiers);
  169.     virtual void    Click( const Point mouse, const short modifiers );
  170.     virtual void    Activate();
  171.     virtual void    Deactivate();
  172.     virtual void    Idle();
  173.     virtual void    Type( const char theKey, const short modifiers );
  174.  
  175.     // command stuff
  176.     
  177.     virtual void    UpdateMenus();
  178.     
  179.     // std edit commands
  180.     
  181.     virtual Boolean    CanPasteType();
  182.     virtual void    DoCut();
  183.     virtual void    DoCopy();
  184.     virtual void    DoPaste();
  185.     virtual void    DoClear();
  186.     virtual void    DoSelectAll();
  187.     
  188.     // dialog handling stuff
  189.     
  190.     virtual void    SetUp();
  191.     virtual void    ClickItem( const short theItem );
  192.     virtual Boolean    CloseDialog();
  193.     virtual Boolean    Filter( EventRecord* theEvent );
  194.     virtual void    DrawUserItem( const short item );
  195.     virtual void    DrawOneItem( const short item );
  196.     virtual void    SetDialogBaseFont( short fontID = 0, short fontSize = 12, short fontStyle = 0 );
  197.     
  198.     // convenience functions
  199.     
  200.     virtual void    SetValue( const short item, const long value );
  201.     virtual void    SetValue( const short item, const int value )     { SetValue(item, (long) value); }
  202.     virtual void    SetValue( const short item, const short value )    { SetValue(item, (long) value); }
  203.     virtual void    SetValue( const short item, const Str255 value );
  204.     virtual void    SetValue( const short item, const double value );
  205.     virtual void    SetValue( const short item, const float value )    { SetValue(item, (double) value); }
  206.     
  207.     virtual long    GetValue( const short item );
  208.     virtual void    GetValueAsText( const short item, Str255 aStr );
  209.     virtual float    GetValueAsFloat( const short item );
  210.     
  211.     virtual short    GetSelectedItemInGroup( const short groupID );
  212.     
  213.     // info about dialog items:
  214.     
  215.     virtual void    GetItemBounds( const short item, Rect* bounds );
  216.     virtual short    GetItemType( const short item );
  217.     virtual short    FindItem( const Point localMouse );
  218.     virtual void    FakeClick( const short item );
  219.     virtual Boolean    HasEditFields();
  220.     virtual Boolean    ValidateItem( const short item, Boolean showAlert = FALSE );
  221.     
  222.     // manipulating items' appearance and behaviour:
  223.     
  224.     virtual void    HiliteItem( const short item, const short state );
  225.     virtual void    OutlineDefaultItem();
  226.     virtual void    HideItem( const short item );
  227.     virtual void    ShowItem( const short item );
  228.     virtual void    EnableItem( const short item );
  229.     virtual void    DisableItem( const short item );
  230.     virtual void    SetEditFieldInfo( const short item, unsigned short iFlags, long iMin = 0, long iMax = 0 );
  231.     virtual void    GetEditFieldInfo( const short item, unsigned short* iFlags, long* iMin = NULL, long* iMax = NULL );
  232.     virtual void    SetItemTitle( const short item, Str255 title );
  233.     virtual void    SelectItem( const short item );
  234.  
  235.     // multi-part dialogs:
  236.     
  237.     virtual void    AppendItemsToDialog( const short ditlID, DITLMethod apMethod = overlayDITL );
  238.     virtual void    RemoveAppendedItems();
  239.     inline    short    GetBaseItemCount() { return baseItems; };
  240.     
  241.     // streaming:
  242.     
  243.     virtual void    WriteToStream( ZStream* aStream );
  244.     virtual void    ReadFromStream( ZStream* aStream );
  245.     
  246.     // d+d:
  247.     
  248.     virtual Boolean        AcceptsFlavour( const OSType aFlavour ) { return FALSE; };
  249.  
  250.     inline    Boolean    IsModal() { return isModal; };
  251.     
  252.     // convenience method for implementing "inline" modal dialogs- use with care!
  253.     
  254.     virtual Boolean    RunModal();
  255.     
  256.     // force modal dialog session to end. Very rarely needed or used.
  257.     
  258.     virtual void    DismissModal( const short itemDismiss );
  259.     
  260.     // ictb stuff:
  261.     
  262.     virtual void    SetTEItemDataFromIctb( const short teItem, Boolean applyChanges = TRUE );
  263.  
  264. protected:
  265.  
  266.     virtual void    MakeMacWindow( const short dialogID );
  267.     virtual void    MakeMacWindow( Rect* aRect, Str255 title, Boolean visible = FALSE, short varCode = 0, Boolean hasCloseBox = FALSE, void* userData = NULL );
  268.  
  269.     virtual void    SetUpUserItems( short fromItemNo = 0 );
  270.     virtual void    SetUpRadioGroups( short fromItemNo = 0 );
  271.     virtual void    ParseRButtonTitle( Str255 buttonTitle, short* groupID, Boolean* isDefault );
  272.     virtual void    HandleRButtonGroupClick( const short item );
  273.     
  274.     virtual void    AddGreyscaleEffects();
  275.     virtual void    ClearDITLPlaceHolders( Handle ditl );
  276.     
  277.     // key and paste data filtering methods, used in conjunction with edit field info:
  278.     
  279.     virtual Boolean    KeyIsLegal( char* theKey, const short targetItem );
  280.     virtual Boolean    PasteDataIsLegal( const short targetItem );
  281.     
  282.     // set up method for edit fields from resources
  283.     
  284.     virtual void    ParseEditFieldInfo( Str255 efText, unsigned short* efFlags, long* min, long* max );
  285. };
  286.  
  287. /*
  288.  
  289. This is a ZWindow that manages a modal or modeless dialog using the dialog manager. For specific
  290. dialogs, you need to override the SetUp, ClickItem and CloseDialog methods to handle your par-
  291. ticular items. The rest is done for you. 
  292.  
  293. Though ZDialog is built upon the Dialog Manager, it extends the feature set of dialogs which make them
  294. much easier to use than the "bare" DM. 
  295. */
  296.  
  297. // method to convert real numbers to strings
  298.  
  299. void RealToString( const double num, Str255& str, short decPlaces = 3 );
  300.  
  301. // compiler flags:
  302.  
  303. // this class can now provide some support for the Apple Grayscale Appearance. If you do not want this
  304. // additional support ( which draws 3D borders around edit fields and list boxes and draws user items as
  305. // a 3D embossed line ), comment out the following compiler flag
  306.  
  307. #define        _GREYSCALE_APPEARANCE    1
  308.  
  309. // static function for drawing 3D effect rectangles:
  310.  
  311. void    FrameGrayRect( Rect* aRect );
  312.  
  313. #define    kFieldRangeAlertID            137
  314.  
  315. #endif